####################################################################
#                                                                  #
# RCBse-10.zip:  FS2004 Selection Correction gauge                 #
#                                                                  #
#                      By Rob Barendregt              3 July 2005  #
#                                                     Release 1.0  #
####################################################################

1. Introduction
===============
Does one of these problems sound familar ??
1. In my multi-engine aircraft, I suddenly find that my throttle controller
   only works for Engine-1, and I cannot correct this by typing (default
   keys) the keysequence E 1 2 (3 4).
2. In my aircraft that has an Exit-2, I cannot open/close Exit-2 by typing
   (default keys) the keysequence Shift-E 2 (instead Exit-1 opens/closes).
If so, adding this invisible gauge to your panel should solve these problems.

For a detailed explanation, see section "The Continuous Event problem".


2. How "Select Engine" and "Select Exit" will work now.
=======================================================
NOTE1: This document assumes that you use the default keystrokes
       for "SelectEngine" (key "E"), "SelectExit" (key "Shift-E"), "SelectItem1"
       ("1") and "SelectItem2" ("2"). Where "1" and "2" are the keys on the text
       part of your keyboard, NOT on the numerical keypad !!.
       If you have assigned other keys instead (see FS2004 menu Options-
       Controls-Assignments), read 'your-key' instead.
NOTE2: "key" means: type this key (not the " !!)

After you have added this gauge to your panel, the behaviour of "SelectEngine" 
and "SelectExit" is a little different, especially timing-wise.

It now works as follows:
- "E" only: after 1 sec, ALL engines are selected. (default FS2004 behaviour:
   Engine-1 is selected immediately).
- "E", followed by the engine number(s) WITHIN ONE SECOND, selects the specified 
   engines.
   E.g. with "E 2 3" typed within one second, Engines 2 and 3 are selected.
- "Shift-E" only: after 1 sec, Exit-1 is toggled.
- "Shift-E", followed by the exit number(s) WITHIN ONE SECOND, opens/closes the
   specified Exit.
   E.g. with "Shift-E 2" typed within one second, Exit-2 is toggled.



3. Installation
===============
1. Extract the files in this archive to a temporary folder.

2. In folder ...\Flight Simulator 9\Gauges\, create a new subfolder \rcb-gauges\
   (if this subfolder does not exists yet).

3. Move file SelectCorrect.xml to folder ...\Flight Simulator 9\Gauges\rcb-gauges\

4. Using e.g. Notepad, add the gauge to the panel.cfg of your aircraft(s).
   Note: only do this for aircraft that have this select Engine/Exit problem.

*** TO BE SAFE, MAKE A BACKUP OF YOUR panel.cfg FIRST ***

In the [VCockpit01] section, OR (if your aircraft does not have a VC) the main 2D
panel window (usually [Window00]) section), add the line:

gauge**=rcb-gauges!SelectCorrect, 0,0

where '**' is the next free number in that section.

IMPORTANT: When you add the gauge to the main 2D panel window, after loading the 
           aircraft you have to make the 2D CockpitView visible at least ONCE 
           before the gauge is actually working !!


4. Background info: The Continuous Event problem in FS2004
==========================================================
For a long history of FS versions, from a functional point-of-view two types of 
commands (called "Events") can be distinguised in FS:
- Single-keystroke commands.
  Examples: 
  - "L" (ToggleAllLights)
  - "S" (CycleViews)
- Multi-keystroke commands.
  Examples: 
  - "E" (SelectEngine), optionally followed by one or more Engine numbers.
  - "Shift-P" (Toggle Pushback), optionally followed by "1" or "2" to select a
    pushback direction.
  - "N" (SelectNAVRadio), followed by "+" or "-" to change the NAV frequency.

These multi-keystroke commands in FS usually select a MODE, meaning that with the 
first key you select the function, and with the next (optional, and/or timelimited)
modifier keys, like "1" or "+", you provide additional information for this function.

Now, selecting such a MODE works fine as long as NO OTHER command is given (either by
the user, a panel gauge, or code in the aircraft model) between the first key and the
modifier keys (with the exception of a few controller AXIS commands).
This explains why, if you e.g. give "Shift-P" for pushback, then change the view with
"S", and then "1" to select a left turn, the aircraft WON't turn: because FS doesn't
relate the "1" and "Shift-P" anymore.
Unfortunately, there are a lot of (addon) gauges around (or even code built into an 
aircraft model itself) that disturb this MODE selection mechanisme because they 
continuously, usually every 55 msec., give FS commands. 
Which causes the problems mentioned above.

<Intermezzo>
A lot of people call this a "bug" in FS; I don't. It's just how FS is implemented,
and IMO gauge/panel developpers should take this behaviour into account.
Although I must admit:
1. The implementation used by Microsoft is a bit "clumsy"; although there IS a need
   to determine to which "function" modifier keys like "1" or "+" belong, there NO
   reason why a "single-keystroke" command should interrupt the "Shift-P" - "1" relation !
   Microsoft could have (should have ?) made a distinction here.
2. Under some conditions it's almost impossible to avoid this "continuous event"
   problem. E.g., a gauge that continuously provides an AXIS command with a new value.
3. The name Select.... for most commands is not very accurate; it not only "selects"
   a function, it also performs an action if NO modifier event is detected.
   Like "E" selects Engine-1 if NO engine number is seen, either because the user
   doesn't type it, or if the sequence is interrupted by another command.
   This is, by the way, the most common cause that you loose the throttles for all
   engines except Engine-1: the user accidentally hits the key assigned to SelectEngine.
</Intermezzo>

Now, the only way to counter-attack this "continuous event" problem, induced by the user
itself or aircraft/gauge programming code, is to make sure that the function command
and following modifier commands cannot be interrupted by other code; i.e. they must
be given at the same instance. And obviously, it's very difficult to type a "2" within
55 msec after typing "E" :-)

And this is exactly what my gauge does (for SelectEngine and SelectExit !!).
E.g. for SelectEngine: when my gauge detects the event SelectEngine, if waits for 
one second, to allow you to type the enginenumber(s). After this second, it issues 
another SelectEngine event, instantaneously followed by the enginenumber(s) select
events. An to make life easier: if NO enginenumber(s) are typed, it selects ALL
enginenumbers (which is, I assume, what you want to do most of the times).

Now, I realise that there are other ways to "solve" this continuous event problem.
Such as:
1. In the registered version of FSUIPC, you have the option "Synchronise Engines".
   However, with this option checked, you cannot select a specific engine if you
   do want to. And after unchecking this option, you still cannot select a specific
   engine (other than Engine-1) if your panel contains a "faulty" gauge.
2. With the registered version of FSUIPC, you can program a controller button or 
   free keyboard key with a specific event sequence; however, you'll need a free
   key/button for each programmed sequence.
3. Some addon panels have a specific gauge for this, e.g. a gauge that (when clicked)
   opens Exit-2.
4. Some (payware) aircraft solve this problem in their own code, by providing you with
   a seperate key-mapping module.

My gauge is generic, and should work for ALL aircraft/panels.
I only implemented this for the most common problems (SelectEngine and SelectExit),
NOT for Pushback. First of all, because it is more complex, secondly because there
are several addons for Pushback around that allready solve this implicitely and 
provide much more additional functionality as well. 
HINT: e.g. my groundhandling gauge package, file rcbgh* 

And for the real FS experts reading the above: I know there's a lot more to say 
about this "issue", but I have to typing somewhere :-)


5. Copyrights and Disclaimer
============================
This gauge is freeware, and available for your personal use.
They may NOT be sold, re-distributed, or (re-)uploaded to another website
(in ANY shape or form) without my explicite, written permission.

If you want to bundle this gauge with your (freeware !!) panel, you 
may do so AFTER my written permission, provided you include this 
README file AS-IS, without modification.
And obviously, installing & using this gauge is at your own risk !!


I hope this gauge solves the problems specified above. It has been tested it with
a lot of aircraft (default and addon), with or without another gauge inducing
this "Continuous Event" problem. I have tried to foresee every possible way these
events might be given, even when given via a mouseclick on a dedicated gauge or 
programmed under a controller button.
But obviously I cannot claim to foresee every combination/permutation :-).

If it doesn't exacly work as specified above, first check that the gauge is 
installed properly and actually loaded:
- Type the key you assigned to "SelectEngine" (default: E)
- Type the key you assigned to "FullThrottle" (default: F4)
- If ONLY Engine-1 is reacting now, the gauge is NOT loaded !!
  (i.e.: YOU did something wrong :-) ).

But PLEASE, before asking me questions, make sure that the answer can not
be found in this README.

Rob Barendregt, The Netherlands
Email: rc.barendregt@planet.nl

               **************************************

